<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>sprox_calypso_sam_c.html</title>
<!-- Source : c:/temp/calypso/sprox_calypso_sam.c -->
<!-- Doc generated on Thu Jun 24 12:26:44 2010 by johann on PC_DEV_5 -->
<!-- Generated with ROBODoc Version 4.99.8 (Specific build by PRO ACTIVE - Apr 13 2010) -->
<style type="text/css">
body
{
  background-color: #ffffff;
  color: #000000;
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  margin-left: 60px;
  margin-right: 40px;  
}
table
{
  border-collapse: collapse;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  margin-bottom: 12px;
}
td
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #dddddd; 
}
th
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;  
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  background-color: #dddddd;  
}
h1
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 18pt;
  font-weight: bold;
  margin-bottom: 36px;
  color: #000000;
  margin-left: -40px;
}
h2
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 12pt;
  font-weight: bold;
  margin-top: 48px;
  margin-bottom: 24px;
  padding-top: 2px;
  padding-bottom: 2px;
  background-color: #dddddd;
  color: #000000;
  margin-left: -40px;
}
h3
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 36px;
  margin-bottom: 24px; 
  border-style: none;
  border-top-style: solid;  
  border-width: 1px;
  border-color: #cccccc; 
  margin-left: -40px;
}
h4
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 24px;
  margin-bottom: 12px;  
}
h5
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  font-weight: bold;
  margin-top: 12px;
  margin-bottom: 2px;  
}
a
{
  color: #0000ff;
}
p
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
ul
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
li
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 550px;
  text-align: justify;
}
tt
{
  font-family: Courier, Courier New;
  font-size: 10pt;
}
pre
{
  background-color: #ffffff;
  color: #000000;
  font-size: 10pt;
}
.NAV
{
  font-size: 7pt;
}
a.NAV
{
  color: #0000cc;
}
.TOC
{
  font-size: 9pt;
  color: #888888;
}
a.TOC
{
  color: #0000ff;
}
.INDEX
{
  font-size: 9pt;
}
a.INDEX
{
  color: #0000ff;
}
.TYPE
{
  font-size: 7pt;
  color: #888888;
}
.ITEM
{
  font-weight: bold;
  color: #000088;
}
.LABEL
{
  color: #000088;
}
.HISTORY
{
  color: #006600;
}
.AUTHOR
{
  color: #006600;
}
.COPYRIGHT
{
  color: #006600;
}
.PORTABILITY
{
  color: #006600;
}
.WARNING
{
  color: #aa0000;
}

.bitinfo
{
  width: 60px;
  font-style: italic;
  text-align: center;
}

.bitnum
{
  text-align: center;
}

.bitname
{
  font-weight: bold;
  text-align: center;
}

.tabitem
{
  width: 100px;
}

.tabname
{
  width: 200px;
}

.tabdesc
{
  width: 450px;
}

.value
{
  font-family: courier;
  text-align: right;
}

.tabsepar
{
  border-top-style: solid;
  border-bottom-style: solid;
  border-width: 2px;
  border-color: #888888;
  font-style: italic;
  text-align: center;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="robo_top_of_doc"></a>
<h3 align="center">TABLE OF CONTENTS</h3>
<ul>
<li><a class="TOC" href="#robo30">CalypsoSam</a></li>
<li><a class="TOC" href="#robo62">SPROX_CalypsoSam_Connect</a></li>
<li><a class="TOC" href="#robo63">SPROX_CalypsoSam_DigestAuthenticate</a></li>
<li><a class="TOC" href="#robo64">SPROX_CalypsoSam_DigestClose</a></li>
<li><a class="TOC" href="#robo65">SPROX_CalypsoSam_DigestInit</a></li>
<li><a class="TOC" href="#robo66">SPROX_CalypsoSam_DigestInit_Old</a></li>
<li><a class="TOC" href="#robo67">SPROX_CalypsoSam_Disconnect</a></li>
<li><a class="TOC" href="#robo68">SPROX_CalypsoSam_Exchange</a></li>
<li><a class="TOC" href="#robo69">SPROX_CalypsoSam_GetChallenge</a></li>
<li><a class="TOC" href="#robo70">SPROX_CalypsoSam_Select</a></li>
<li><a class="TOC" href="#robo71">SPROX_CalypsoSam_SelectDiversifier</a></li>
</ul>
<h3>&nbsp;</h3>


<h1><a name="robo30"><span class="TYPE">[Modules]</span><a class="LABEL" name="CalypsoSam">
CalypsoSam</a></h1>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./modules.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   SpringProxAPI :: Working with Calypso SAMs
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Most parameters of the SPROX_CalypsoSam_xxx functions directly map to Calypso
   SAM internal functions.
   Please refer to Calypso official documentation for any details.
</pre>
</span>


<h2><a name="robo62"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fConnect">
SPROX_CalypsoSam_Connect</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_Connect</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Connect to a Calypso SAM in the currently select slot

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_Connect</strong>(BYTE atr_buffer[],
                                  WORD *atr_length);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   WORD *atr_length         : max size for atr_buffer

 OUTPUTS
   BYTE  atr_buffer[]       : ATR of the found SAM (if one)
   WORD *atr_length         : size of SAM's ATR
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo70">SPROX_CalypsoSam_Select</a>
   <a class="LINK_37" href="#robo67">SPROX_CalypsoSam_Disconnect</a>
</pre>
</span>


<h2><a name="robo63"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fDigestAuthenticate">
SPROX_CalypsoSam_DigestAuthenticate</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_DigestAuthenticate</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Verify the MAC returned by the card after closing the secure session

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_DigestAuthenticate</strong>(BYTE card_mac[4]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  card_mac[4]        : the message authentication code provided by the Calypso card
                              in answer to <a class="LINK_12" href="./sprox_calypso_card_c.html#robo56">SPROX_Calypso_CloseSecureSession</a>
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   <a class="LINK_21" href="./sprox_calypso_h.html#robo90">CALYPSO_WRONG_MAC</a>        : bad signature (invalid card_mac)
   Other code on any error
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Error <a class="LINK_23" href="./sprox_calypso_h.html#robo90">CALYPSO_WRONG_MAC</a> denotes a fatal security error.
   As this comes after a successfull call to <a class="LINK_23" href="./sprox_calypso_card_c.html#robo56">SPROX_Calypso_CloseSecureSession</a>, the
   card did accepted our cryptogram, but replied with an invalid one.
   This must mean that the card has been forged !!!
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_calypso_card_c.html#robo56">SPROX_Calypso_CloseSecureSession</a>
   <a class="LINK_37" href="#robo64">SPROX_CalypsoSam_DigestClose</a>
</pre>
</span>


<h2><a name="robo64"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fDigestClose">
SPROX_CalypsoSam_DigestClose</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_DigestClose</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Ask the SAM to generate the certificate to send to the card to close a session

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_DigestClose</strong>(BYTE sam_mac[4]);

 OUTPUTS
   BYTE  sam_mac[]          : MAC computed by the SAM, to be forwarded to the card
                              through <a class="LINK_6" href="./sprox_calypso_card_c.html#robo56">SPROX_Calypso_CloseSecureSession</a>
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_calypso_card_c.html#robo56">SPROX_Calypso_CloseSecureSession</a>
   SPROX_CalypsoSam_DigestOpen
</pre>
</span>


<h2><a name="robo65"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fDigestInit">
SPROX_CalypsoSam_DigestInit</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_DigestInit</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Activates a session in the SAM, and initializes its digest

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_DigestInit</strong>(BYTE kif,
                                     BYTE kvc,
                                     BYTE card_resp_buffer[],
                                     WORD card_resp_length);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  kif                : key identifier
   BYTE  kvc                : key version (as returned by the card in answer to
                              <a class="LINK_12" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a> with P1's bit 7 set)
   BYTE  card_resp_buffer[] : card's answer to <a class="LINK_12" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
   WORD  card_resp_length   : size of card's answer 
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo66">SPROX_CalypsoSam_DigestInit_Old</a>
   <a class="LINK_37" href="#robo69">SPROX_CalypsoSam_GetChallenge</a>
   <a class="LINK_37" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
   <a class="LINK_37" href="#robo64">SPROX_CalypsoSam_DigestClose</a>
</pre>
</span>


<h2><a name="robo66"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fDigestInit5fOld">
SPROX_CalypsoSam_DigestInit_Old</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_DigestInit_Old</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Activates a session in the SAM, and initializes its digest, using absolute
   record number to select the key

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_DigestInit_Old</strong>(BYTE key_record,
                                         BYTE card_resp_buffer[],
                                         WORD card_resp_length);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  key_record         : key record number
   BYTE  card_resp_buffer[] : card's answer to <a class="LINK_12" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
   WORD  card_resp_length   : size of card's answer 
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo65">SPROX_CalypsoSam_DigestInit</a>
   <a class="LINK_37" href="#robo69">SPROX_CalypsoSam_GetChallenge</a>
   <a class="LINK_37" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
   <a class="LINK_37" href="#robo64">SPROX_CalypsoSam_DigestClose</a>
</pre>
</span>


<h2><a name="robo67"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fDisconnect">
SPROX_CalypsoSam_Disconnect</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_Disconnect</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Disconnect from the currently active Calypso SAM

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_Disconnect</strong>(void);
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo62">SPROX_CalypsoSam_Connect</a>
</pre>
</span>


<h2><a name="robo68"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fExchange">
SPROX_CalypsoSam_Exchange</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_Exchange</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Exchange an APDU with the currently active Calypso SAM

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_Exchange</strong>(BYTE send_buffer[],
                                   WORD send_length,
                                   BYTE recv_buffer[],
                                   WORD *recv_length);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  send_buffer[]      : APDU to be sent to the SAM
   WORD  send_length        : size of the APDU to be sent
   WORD *recv_length        : max size for recv_buffer
 
 OUTPUTS
   BYTE  recv_buffer[]      : SAM's answer
   WORD *recv_length        : size of SAM's answer
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SIDE EFFECTS</p>
<span class="SIDE_EFFECTS"><pre class="SIDE EFFECTS">   Result of SPROX_CalypsoSam_SW is updated with last status word
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo62">SPROX_CalypsoSam_Connect</a>
</pre>
</span>


<h2><a name="robo69"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fGetChallenge">
SPROX_CalypsoSam_GetChallenge</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_GetChallenge</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Ask SAM to create a new nounce in order to open a secure session with a card

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_GetChallenge</strong>(BYTE sam_chal[4]);

 OUTPUTS
   BYTE  sam_chal[4]        : SAM's nounce, to be forwarded to the card in
                              <a class="LINK_6" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   SPROX_CalypsoSam_SelectDiversifier_Atr
   <a class="LINK_37" href="./sprox_calypso_card_c.html#robo60">SPROX_Calypso_OpenSecureSession</a>
   <a class="LINK_37" href="#robo65">SPROX_CalypsoSam_DigestInit</a>
</pre>
</span>


<h2><a name="robo70"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fSelect">
SPROX_CalypsoSam_Select</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_Select</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Select the smartcard slot where the Calypso SAM is to be found

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_Select</strong>(BYTE slot);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE slot                : smarcard slot number
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Slot # 0 to 8 map to contact slots :
   0 = main slot (ISO 7816 size)
   1 = first SAM slot (micro SIM size)
   2 = second SAM slot
   ...
</pre>
</span>


<h2><a name="robo71"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypsoSam5fSelectDiversifier">
SPROX_CalypsoSam_SelectDiversifier</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_CalypsoSam_SelectDiversifier</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Feed the SAM with current card's UID

 SYNOPSYS
   SWORD <strong>SPROX_CalypsoSam_SelectDiversifier</strong>(BYTE card_uid[8]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  card_uid[8]        : serial number of the Calypso card, as returned by
                              <a class="LINK_12" href="./sprox_calypso_card_c.html#robo57">SPROX_Calypso_Connect</a>
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo69">SPROX_CalypsoSam_GetChallenge</a>
</pre>
</span>
<hr />
Generated from <b>sprox_calypso_sam.c</b> on Thu Jun 24 12:26:44 2010<br />
</body>
</html>
